ZeroAllocPool for Godot 4.6+

A high-performance, memory-optimized Static Index Free-List Pool implemented in native C++ via GDExtension.

Designed specifically for performance-critical indie games (bullet hells, massive particle systems, enemy spawner systems) where runtime heap allocations and Garbage Collector spikes can ruin fluid gameplay.

Key Features

- True Zero-Allocation: Reserves a contiguous block of memory linearly at level load. Zero `new` or `malloc` operations during runtime.

- CPU Cache Locality: Data is stored back-to-back in memory, minimizing CPU cache misses and maximizing hardware processing speed.

- O(1) Time Complexity: Fetching (`obtain`) and recycling (`release`) available slots takes constant time, regardless of pool size.

- GDScript Friendly: Exposes a clean, high-speed index management API directly to your GDScript architecture without SceneTree overhead.

How to Compile From Source

If you want to modify the C++ code or compile for other platforms (Linux, macOS, Mobile, Consoles), use the included SCons script.

Requirements:

• Python 3.x
• SCons (pip install scons)
• A compatible C++ compiler (MSVC, GCC, or Clang)

Commands:

Inside the `source/` directory, run:

# For Windows Debug Binary
scons platform=windows target=template_debug
# For Windows Release Binary (Optimized)
scons platform=windows target=template_release

The script will compile and automatically output the new binaries into the `addons/zero_alloc_pool/bin/` folder.

API Reference

void initialize(int capacity)

Allocates the memory pool upfront with the specified maximum capacity and chains the internal free-list indices. Call this once during initialization (e.g., in `_ready()`).

int obtain()

Returns the next available array index in O(1) time. If the pool is full, it pushes an error to the Godot console and returns -1.

void release(int index)

Recycles the slot at the specified index in O(1) time, making it immediately available for future allocations.

int get_available_count()

Returns the number of remaining free slots in the pool.

int get_active_count()

Returns the number of slots currently active and in use.

Code Example (GDScript)

Pre-instantiate your visual nodes or data structures into a flat array during game loading, and let `ZeroAllocPool` handle high-speed indexing:

extends Node2D
const MAX_BULLETS = 1000
@onready var bullet_scene = preload("res://Bullet.tscn")
var pool: ZeroAllocPool
var bullet_nodes: Array[Node2D] = []
func _ready() -> void:
    # 1. Instantiate the native C++ pool
    pool = ZeroAllocPool.new()
    pool.initialize(MAX_BULLETS)
    
    # 2. Warm up cache by instantiating nodes upfront
    for i in range(MAX_BULLETS):
        var bullet = bullet_scene.instantiate()
        bullet.visible = false
        add_child(bullet)
        bullet_nodes.append(bullet)
func spawn_bullet(global_spawn_pos: Vector2) -> void:
    # Get a free slot index in O(1)
    var idx = pool.obtain()
    
    if idx != -1:
        var bullet = bullet_nodes[idx]
        bullet.global_position = global_spawn_pos
        bullet.visible = true
        bullet.set_meta("pool_index", idx) # Store index to release it later
func remove_bullet(bullet: Node2D) -> void:
    var idx = bullet.get_meta("pool_index")
    bullet.visible = false
    
    # Release back to C++ free-list in O(1)
    pool.release(idx)